Creating and Configuring Access Control Policies and Statements

Access control policies are the basic organizational unit of activity access controls. Policies act as containers for access control statements, and are also used to apply those statements to specified users.

To set up access controls, you:

  1. Create policies to contain a set of access permissions (statements)

  2. Add statements to a policy to define specific access permissions

  3. Link users or teams to a policy to apply its permission to those users

This article provides instructions on how to complete each of these steps. It also provides best practices for testing your access control policies and statements to make sure they are working as expected.

Create an Access Control Policy

You can create as many access control policies as you need. Policies have no effect until they contain at least one valid statement and are linked to at least one user or team.

To create a new access control policy, follow these steps:

  1. Open the access control policies settings.

  2. On the Policies page, click + Create Policy.

    The Create Policy dialog opens.

  3. Enter a name for the policy into the Name field.

    • This field is required.

    • The policy name is displayed prominently on the Policies page. We recommend choosing a name that briefly describes the purpose or scope of the policy for easy identification at a glance.

  4. Optional: Enter a brief description of the policy (e.g. its intended purpose) into the Description field.

    • You can enter a maximum of 100 characters into this field.

    • The policy description is displayed (on hover) as a tooltip beside the policy name on the Policies page.

  5. Click Save to finish creating the new policy.

    The Create Policy dialog closes and the Policies page is displayed, where the newly created policy is displayed at the bottom of the list.

You have successfully created a new policy. Next, you can add statements to the policy. Alternatively, you can link users or teams to the policy first, and add statements later.

Add Statements to an Access Control Policy

Statements define the scope of permissions covered by a policy. Each statement consists of four properties:

  • Effect (required): Specifies what effect the statement has when it is applied, e.g. the statement allows the user to perform the specified action on the specified resource.

  • Resource (required): Specifies the type of Plan resource the statement applies to, e.g. all or specified activity types.

  • Action (required): Specifies the resource-based action that the statement applies to, e.g. viewing an activity's details.

  • Conditions (Optional): Specifies additional resource-based conditions to further define the statement's scope, e.g. only activities that have a specified attribute value.

For example, a statement might allow (effect) a user to view (action) any activity (resource) which has the activity type "Tactic" (condition).

You can add as many statements to a policy as necessary. When evaluating the policies that apply to a user, the access control system adds the permission scopes from all applicable policies together, and applies the sum to the user.

Example

A user has two applicable policies: one policy grants full access to a resource, while the other policy does not contain any statements about that resource.

The second policy is effectively the same as the user having no access to the resource (under the "deny by default" principle). However, the user would still have access to the resource through the first policy, because the effect of multiple policies is additive, and the user receives the sum of permission scopes.

To add a statement to an access control policy, follow these steps:

  1. Open the access control policies settings.

  2. On the Policies page, find the policy you want to add a statement to. On the policy, click Create statement:

    The Create Statement dialog opens, with the Statement Editor tab displayed.

  3. On the Statement Editor tab, use the Effect field to select the effect that the statement has.

    Note

    Currently, the only available effect is ALLOW, which means the access defined by the statement is granted to linked users.

  4. Use the Resource field to select the resource that the statement applies to.

  5. Use the Action field to select the action that the statement applies to.

  6. Optional: To add conditions, click the Raw JSON tab to switch to the JSON editor view. In the JSON editor, add a conditions array to define and specify conditions.

    Note

    Advanced users can configure all aspects of a statement using JSON (JavaScript Object Notation) syntax. Currently, conditions are only supported in the JSON editor, which means that you must use JSON to add and configure conditions.

    Note that when you set conditions on a statement (with the JSON editor), this deactivates the Statement Editor tab for that statement. This means that, after you add conditions to a statement, you can only make further changes to that statement with the JSON editor.

  7. Click Save to finish creating the statement.

    The Create Statement dialog closes and the Policies page is displayed, where the newly created statement appears in the expanded view of the policy where it was created (click the Expand button on the policy's entry to view its details).

You have successfully added a statement to a policy. Repeat these steps to add additional statements, if needed. Next, you can put the policy and its statements into effect by linking users or teams to the policy.

Link Users and Teams to an Access Control Policy

To apply the statements (permissions) contained in an access control policy to users in your Uptempo environment, you must link users to the policy.

You can choose to link users to a policy either individually, as part of a team (linking a team links all users within the team), or both. You can link as many users or teams to a policy as needed. You can link (or unlink) users at any time, and the change in access will take effect immediately.

To link users (either individually, or as a team) to an access control policy, follow these steps:

  1. Open the access control policies settings.

  2. On the Policies page, find the policy you want to link a user or team to. On the policy's entry, click the Expand button to view its details.

  3. In the expanded view of the policy, click Link users/teams.

    The Link Users/Teams dialog opens.

  4. Select the users you want to add to the policy:

    • To select and add all users on a team to the policy: Select the team from the list under Select one or more teams.

    • To select and add individual users to the policy: Select the user from the list under Select one or more users.

    • You can type keywords into both list fields to filter the respective list and display only matching teams or users.

    • After you select a team or user, it appears in the list field. To remove a selected team or user, click Remove on their entry in the respective field.

    • Add multiple teams or users by selecting additional items in the respective list.

  5. Click Link Users to link the selected users to the policy.

    The Link Users/Teams dialog closes and the Policies page is displayed, where the added users or teams are listed in the expanded view of the policy.

You have successfully linked users to a policy, and the policy's statements will take effect for the linked users immediately.

Testing Access Control Policies

To ensure that access control policies are working as intended, we recommend using the following procedure to test newly created policies (or planned changes to existing policies) before enabling them for users in production:

  1. Create a special "test" user account that is different from your regular (administrator) user account.

  2. Create a new policy and add all required statements to it. This will act as the "draft" version of the new policy.

    • For visibility, we recommend naming the new policy in a way that clearly marks it as a "draft" version.

    • If you want to make changes to an existing policy's statements, recreate the existing policy's statements in the new "draft" policy, along with any changes you want to implement — do not make changes to the existing policy at this stage.

  3. When you are ready to test the "draft" policy, link only the "test" user to it.

  4. Sign in to your Uptempo instance as the "test" user, and test the access control policy by interacting with the Plan module.

    Tip

    If possible, sign in to the "test" user account in an incognito browser window, while remaining signed in to your administrator user account in another (non-incognito) browser window. This allows you to make configuration changes with the administrator user account and immediately test them with the "test" user account.

  5. When you have confirmed that the policy is working as intended, unlink the "test" user from it.

    • This helps to prevent problems when you use the "test" user with new policies in the future: if the "test" user is still inadvertently linked to older policies, this can cause unexpected and invalid results during testing (as all linked policies take effect in an additive fashion).

  6. Link users/teams to the "draft" policy to activate it.

    • At this point, the new policy is no longer in draft, so you should update the name accordingly if applicable.

    • If you are making changes to an existing policy's statements, switch the users/teams linked to the existing policy over to the new policy (i.e. the former "draft" policy). To do this, first link the users/teams to the new policy, then unlink them from the old policy.

      Important

      Do not delete the old policy yet! Leave it in place for now, so that you can revert to it if there are problems with the new policy. After you have confirmed that the new policy is working in production as expected, you can delete the old policy.